Skip to main content

Configure dorcha-gateway for your infrastructure

Configuration files define how the dorcha-gateway operates, which AI services it is allowed pass through requests to, and what security measures are enforced. The gateway validates your configuration on startup and provides clear error messages for any issues. dorcha-gateway uses JSON configuration files to define its behavior, security policies, and integration settings. This guide provides comprehensive coverage of all configuration options, with practical examples and security considerations for different deployment scenarios.

tip

See the [Supported AI models](/docs/Agentic Gateway/supported_models) section to see what models can currently be configured with dorcha-gateway.

Network Settings​

The gateway requires basic network configuration to determine where and how it listens for requests.

Host Binding The host field specifies which network interface the gateway binds to. For local development, use "localhost" to restrict access to the local machine. In production environments, you may need to bind to "0.0.0.0" to accept connections from external clients.

Port Configuration The gateway uses two ports: a proxy port (port) for AI service requests and a management port (management_port) for administrative functions.

HTTPS Support When use_https is enabled, the gateway requires TLS certificate and private key files. This is essential for production deployments to ensure encrypted communication between clients and the gateway.

Logging​

The log_level field controls the verbosity of gateway logs. Available levels include debug, info, warn, and error. In production, info provides a good balance of visibility and performance, while debug is useful for troubleshooting development issues.

Authentication​

Authentication in Dorcha uses HMAC-based signatures to verify client identity and authorize access to AI services. When auth_enabled is true, all requests must include properly signed security headers. The authentication system validates that clients have permission to access specific AI services based on defined policies. This prevents unauthorized access and provides audit trails for compliance requirements.

Authentication Policies Policies define which internal entities can communicate with which AI services. Each policy specifies the client entity, target service, communication direction, and access permissions. Policies can include expiration dates and additional conditions for fine-grained access control.

Policy Structure Each policy contains several key components. The internal_entity identifies the client making the request, typically with an ID and type classification. The agentic_service specifies the target AI service, including its identifier, type, and base URL.

Communication direction determines the flow of requests. outbound_only allows clients to send requests to AI services, inbound_only permits AI services to initiate communication with clients, and bidirectional enables two-way communication patterns.

Audit Logging​

Audit logging provides cryptographically signed records of all gateway activity. When enabled, the gateway logs every request with detailed metadata including client identity, service accessed, content analysis results, and security decisions.

Audit Configuration The audit system can be configured with different log levels and formats. JSON formatting is recommended for production environments as it enables easy parsing and analysis by log aggregation systems.

Cryptographic Signing Audit logs are cryptographically signed to ensure integrity and prevent tampering. This is crucial for compliance requirements and security investigations.

Content Validation​

The gateway includes built-in validators to scan and analyze request content for security threats and policy violations.

Prompt Injection Detection The promptdetection validator identifies attempts to manipulate AI models through prompt injection techniques. This includes patterns like "ignore previous instructions" and other common injection attempts.

Secrets Detection The secretsdetection validator scans request content for sensitive information such as API keys, passwords, and other credentials. This helps prevent accidental exposure of sensitive data through AI service requests.

Service Configuration​

Each AI service requires a unique identifier, type classification, and base URL. The identifier is used in authentication policies and client requests to route traffic to the correct service. Service URLs should point to the base API endpoint, not specific model endpoints. The gateway handles path construction and request forwarding automatically.

Response Behavior Configuration​

When content validation detects policy violations, the gateway can be configured to respond in different ways depending on your application requirements. By default, the gateway sends HTTP Status 403 Forbidden on all violations, without providing any details on the violation. However, this behavior can be configured by the following two knobs.

Detailed Responses The send_forbidden_response_to_client option determines whether violation details are included in error responses. This can be useful for debugging but may expose internal security logic to clients.

Tool Compatibility Some AI testing tools expect successful responses even when violations occur. The send_status_ok_response_on_violation option returns HTTP 200 status codes with violation information embedded in the response body, enabling tools like Goose to continue processing.

Examples​

Development​

For development and testing environments, a minimal configuration provides basic functionality without complex security requirements.

{
    "host": "localhost",
    "data_plane_port": 3128,
    "control_plane_port": 3129,
    "log_level": "info",
    "use_https": false,
    "audit_enabled": false,
    "auth_enabled": false,
    "agentic_services": [
        {
            "id": "ollama",
            "type": "ollama",
            "url": "http://localhost:11434"
        }
    ],
    "validators": [
        "promptdetection",
        "secretsdetection"
    ]
}

This configuration enables local development with Ollama models while maintaining content validation for security testing.

Production Configuration​

Production environments require comprehensive security measures and proper TLS configuration.

{
    "host": "0.0.0.0",
    "data_plane_port": 3128,
    "control_plane_port": 3129,
    "log_level": "info",
    "use_https": true,
    "cert_file": "/etc/dorcha/cert.pem",
    "key_file": "/etc/dorcha/key.pem",
    "audit_enabled": true,
    "auth_enabled": true,
    "audit_config": {
        "signing": {
            "enabled": true,
            "key_path": "/etc/dorcha/audit-signing.key"
        },
        "settings": {
            "log_level": "info",
            "log_format": "json"
        }
    },
    "auth_config": {
        "policies": {
            "web_service_policy": {
                "policy_id": "web_service_policy",
                "internal_entity": {
                    "id": "web-service-1",
                    "type": "web-service"
                },
                "agentic_service": {
                    "id": "openai",
                    "type": "openai",
                    "url": "https://api.openai.com/v1"
                },
                "direction": "outbound_only",
                "allowed": true,
                "reason": "Web service can access OpenAI API"
            }
        }
    },
    "agentic_services": [
        {
            "id": "openai",
            "type": "openai",
            "url": "https://api.openai.com/v1"
        }
    ],
    "validators": [
        "promptdetection",
        "secretsdetection"
    ]
}

This configuration provides enterprise-grade security with authentication, audit logging, and TLS encryption.